Add documentation about OpenXR spatial entities #11015

BastiaanOlij · 2025-06-11T06:14:11Z

This PR adds documentation for the spatial entities implementation being added here: godotengine/godot#107391

JD-The-65th

I noticed a few grammatical issues and typos so I wanted to make a review addressing some of them. I saw that it was also a commonality in this PR to omit commas after dependent clauses, so I left in 2 cases where I noticed it occurred, but I can go back and mark more where I noticed them.

tutorials/xr/openxr_spatial_entities.rst

AThousandShips

Will do a pass to improve sentence structure as well later

tutorials/xr/openxr_spatial_entities.rst

BastiaanOlij · 2025-07-16T01:17:10Z

Thanks for the feedback everyone, just to let you all know, I'm planning on updating this PR after we're certain about the API on the implementation PR just to minimize having to go back and forth on those changes. Will be updating this PR soonish

BastiaanOlij · 2025-08-06T05:56:49Z

tutorials/xr/openxr_spatial_entities.rst

+
+
+    **
+        Q : Should we be doing update queries here to get position changes for markers??


Mostly a reminder to myself, I need to add this in. We now do this in the built-in logic as well.

BastiaanOlij · 2025-08-06T05:57:31Z

I think I covered all the comments, only some outstanding stuff around parameter naming which remains a problem.

Also need to find some time to add update queries to the marker example.

AThousandShips

Some suggestions for breaking up the sentences, can look at more cases later

AThousandShips · 2025-08-07T13:35:50Z

tutorials/xr/openxr_spatial_entities.rst

+how they are found, and how information about them is stored and accessed.
+
+Various extensions are added on top that implement specific systems such as marker tracking,
+plane tracking and anchors. These are referred to as spatial capabilities.


Suggested change

plane tracking and anchors. These are referred to as spatial capabilities.

plane tracking, and anchors. These are referred to as spatial capabilities.

AThousandShips · 2025-08-07T13:36:00Z

tutorials/xr/openxr_spatial_entities.rst

+Various extensions are added on top that implement specific systems such as marker tracking,
+plane tracking and anchors. These are referred to as spatial capabilities.
+
+Each entity that can be handled by the system is broken up into smaller components which makes it easy


Suggested change

Each entity that can be handled by the system is broken up into smaller components which makes it easy

Each entity that can be handled by the system is broken up into smaller components, which makes it easy

AThousandShips · 2025-08-07T13:37:33Z

tutorials/xr/openxr_spatial_entities.rst

+All entity trackers will expose their location through the ``default`` pose.
+
+We can automate creating these subscenes and adding them to our scene tree by creating a manager
+object. As all locations are local to the :ref:`XROrigin3D<class_XROrigin3D>` node we should create


Suggested change

object. As all locations are local to the :ref:`XROrigin3D<class_XROrigin3D>` node we should create

object. As all locations are local to the :ref:`XROrigin3D<class_XROrigin3D>` node, we should create

AThousandShips · 2025-08-07T13:37:44Z

tutorials/xr/openxr_spatial_entities.rst

+each type of entity.
+
+Generally speaking we will instance different subscenes for each type of entity.
+As the tracker objects can be used with :ref:`XRAnchor3D<class_XRAnchor3D>` nodes these subscenes


Suggested change

As the tracker objects can be used with :ref:`XRAnchor3D<class_XRAnchor3D>` nodes these subscenes

As the tracker objects can be used with :ref:`XRAnchor3D<class_XRAnchor3D>` nodes, these subscenes

AThousandShips · 2025-08-07T13:40:45Z

tutorials/xr/openxr_spatial_entities.rst

+Alternatively we can assign a material that will visualize the plane for debugging.
+
+We configure this material as the ``material_override`` material on our MeshInstance3D.
+For our "hole punch" material create a :ref:`ShaderMaterial<class_ShaderMaterial>`


Suggested change

For our "hole punch" material create a :ref:`ShaderMaterial<class_ShaderMaterial>`

For our "hole punch" material, create a :ref:`ShaderMaterial<class_ShaderMaterial>`

AThousandShips · 2025-08-07T13:54:32Z

tutorials/xr/openxr_spatial_entities.rst

+OpenXR spatial entities
+=======================
+
+For any sort of augmented reality application you need to access real world information and be able to


Suggested change

For any sort of augmented reality application you need to access real world information and be able to

For any sort of augmented reality application you need to access real world information, and be able to

AThousandShips · 2025-08-07T13:55:04Z

tutorials/xr/openxr_spatial_entities.rst

+    Note that various XR devices also require permission flags to be set. These will need to be
+    enabled in the export preset settings.
+
+Enabling the different capabilities activates the related OpenXR APIs but additional logic is needed


Suggested change

Enabling the different capabilities activates the related OpenXR APIs but additional logic is needed

Enabling the different capabilities activates the related OpenXR APIs, but additional logic is needed

AThousandShips · 2025-08-07T13:55:19Z

tutorials/xr/openxr_spatial_entities.rst

+For each core system we have built-in logic that can be enabled that will do this for you.
+
+We'll discuss the spatial entities system under the assumption the built-in logic is enabled first.
+We will then take a look at the underlying APIs and how you can implement this yourself however it


Suggested change

We will then take a look at the underlying APIs and how you can implement this yourself however it

We will then take a look at the underlying APIs and how you can implement this yourself, however it

AThousandShips · 2025-08-07T13:56:24Z

tutorials/xr/openxr_spatial_entities.rst

+When a spatial anchor has been made persistent, a Universally Unique Identifier (or UUID) is
+assigned to the anchor. You will need to store this with whatever information you need to
+reconstruct the scene.
+In our example code below we'll simply call ``set_scene_path`` and ``get_scene_path`` but you


Suggested change

In our example code below we'll simply call ``set_scene_path`` and ``get_scene_path`` but you

In our example code below we'll simply call ``set_scene_path`` and ``get_scene_path``, but you

AThousandShips · 2025-08-07T13:56:54Z

tutorials/xr/openxr_spatial_entities.rst

+    "unpersistent" and then clean up the anchor.
+    Also you will get an error if you try to destroy an anchor that is still persistent.
+
+To complete our anchor system we start with creating a scene that we'll set as the scene


Suggested change

To complete our anchor system we start with creating a scene that we'll set as the scene

To complete our anchor system we start by creating a scene that we'll set as the scene

BastiaanOlij added this to the 4.x milestone Jun 11, 2025

BastiaanOlij self-assigned this Jun 11, 2025

BastiaanOlij added enhancement topic:xr Related to XR documentation labels Jun 11, 2025

BastiaanOlij mentioned this pull request Jun 11, 2025

OpenXR: Add support for spatial entities extension godotengine/godot#107391

Open

AThousandShips added the waiting on PR merge PR's that can't be merged until an engine PR is merged first label Jun 11, 2025

JD-The-65th suggested changes Jun 11, 2025

View reviewed changes

AThousandShips removed this from the 4.x milestone Jun 12, 2025

AThousandShips reviewed Jun 24, 2025

View reviewed changes

BastiaanOlij force-pushed the openxr_spatial_entities_docs branch 6 times, most recently from 27ac884 to a5b0b4a Compare August 6, 2025 05:54

Add documentation about OpenXR spatial entities

4edb00e

BastiaanOlij force-pushed the openxr_spatial_entities_docs branch from a5b0b4a to 4edb00e Compare August 6, 2025 05:56

BastiaanOlij commented Aug 6, 2025

View reviewed changes

AThousandShips reviewed Aug 7, 2025

View reviewed changes



		**
		Q : Should we be doing update queries here to get position changes for markers??

	plane tracking and anchors. These are referred to as spatial capabilities.
	plane tracking, and anchors. These are referred to as spatial capabilities.

	Each entity that can be handled by the system is broken up into smaller components which makes it easy
	Each entity that can be handled by the system is broken up into smaller components, which makes it easy

	object. As all locations are local to the :ref:`XROrigin3D<class_XROrigin3D>` node we should create
	object. As all locations are local to the :ref:`XROrigin3D<class_XROrigin3D>` node, we should create

	As the tracker objects can be used with :ref:`XRAnchor3D<class_XRAnchor3D>` nodes these subscenes
	As the tracker objects can be used with :ref:`XRAnchor3D<class_XRAnchor3D>` nodes, these subscenes

	For our "hole punch" material create a :ref:`ShaderMaterial<class_ShaderMaterial>`
	For our "hole punch" material, create a :ref:`ShaderMaterial<class_ShaderMaterial>`

	For any sort of augmented reality application you need to access real world information and be able to
	For any sort of augmented reality application you need to access real world information, and be able to

	Enabling the different capabilities activates the related OpenXR APIs but additional logic is needed
	Enabling the different capabilities activates the related OpenXR APIs, but additional logic is needed

	We will then take a look at the underlying APIs and how you can implement this yourself however it
	We will then take a look at the underlying APIs and how you can implement this yourself, however it

	In our example code below we'll simply call ``set_scene_path`` and ``get_scene_path`` but you
	In our example code below we'll simply call ``set_scene_path`` and ``get_scene_path``, but you

	To complete our anchor system we start with creating a scene that we'll set as the scene
	To complete our anchor system we start by creating a scene that we'll set as the scene

Uh oh!

Add documentation about OpenXR spatial entities #11015

Are you sure you want to change the base?

Add documentation about OpenXR spatial entities #11015

Conversation

BastiaanOlij commented Jun 11, 2025

Uh oh!

JD-The-65th left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AThousandShips left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BastiaanOlij commented Jul 16, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BastiaanOlij commented Aug 6, 2025

Uh oh!

AThousandShips left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!